BCI NET

home *** CD-ROM | disk | FTP | other *** search

/ BCI NET / BCI NET Dec 94.iso / archives / programming / source / jade-3.2.lha / jade-3.2 / man / jade.info-5 < prev next >

Wrap

GNU Info File | 1994-10-16 | 48.5 KB | 1,312 lines

This is Info file jade.info, produced by Makeinfo-1.55 from the input file jade.texi. START-INFO-DIR-ENTRY * Jade: (jade). An editor for X11 and AmigaDOS END-INFO-DIR-ENTRY This is Edition 1.3, last updated 7 October 1994, of `The Jade Manual', for Jade, Version 3.2. Jade is a text editor for X11 (on Unix) and the Amiga. Copyright 1993, 1994 John Harper. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. File: jade.info, Node: Control Structures, Next: Variables, Prev: Evaluation, Up: Programming Jade Control Structures ================== Control structures are special forms or macros which control which forms get evaluated, when they get evaluated and the number of times to evaluate them. This includes conditional structures, loops, etc... The simplest control structures are the sequencing structures; they are used to evaluate a list of forms in left to right order. * Menu: * Sequencing Structures:: Evaluating several forms in sequence * Conditional Structures:: Making decisions based on truth values * Looping Structures:: `while' loops * Non-Local Exits:: Exiting from several levels of evaluation File: jade.info, Node: Sequencing Structures, Next: Conditional Structures, Up: Control Structures Sequencing Structures --------------------- Each of the special forms in this section simply evaluates its argument forms in left-to-right order. The only difference is the result they return. The most widely used sequencing special form is `progn': it evaluates all its argument forms and returns the computed value of the last one. Many other control structures are said to perform an "implicit progn", this means that they call `progn' with a list of forms. `progn' in Lisp is nearly analogous to a `begin...end' block in Pascal; it is used in much the same places -- to allow you to evaluate a sequence of form where only one form was allowed (for example the true clause of an `if' structure). - Special Form: progn FORMS... All of the FORMS are evaluated sequentially (from left-to-right), the result of the last evaluated FORM is the return value of this structure. If no arguments are given to `progn' it returns `nil'. (progn 'one (+ 1 1) "three") => "three" (progn) => nil - Special Form: prog1 FIRST FORMS... This special form evaluates its FIRST form then performs an implicit progn on the rest of its arguments. The result of this structure is the computed value of the first form. (prog1 'one (+ 1 1) "three") => one - Special Form: prog2 FIRST SECOND FORMS... This is similar to `prog1' except that the evaluated value of its SECOND form is returned. The FIRST form is evaluated, then its SECOND, then it performs an implicit progn on the remaining arguments. (prog2 'one (+ 1 1) "three") => 2 File: jade.info, Node: Conditional Structures, Next: Looping Structures, Prev: Sequencing Structures, Up: Control Structures Conditional Structures ---------------------- Lisp provides a number of conditional constructs, the most complex of which (`cond') will take a list of conditions, the first of which is `t' then has its associated list of forms evaluated. Theoretically this is the only conditional special form necessary -- the rest could be implemented as macros. - Special Form: if CONDITION TRUE-FORM ELSE-FORMS... The `if' construct is the nearest thing in Lisp to the "if-then-else" construct found in most programming languages. First the CONDITION form is evaluated, if it returns `t' (not `nil') the TRUE-FORM is evaluated and its result returned. Otherwise the result of an implicit progn on the ELSE-FORMS is returned. If there are no ELSE-FORMS `nil' is returned. Note that one of the TRUE-FORM or the ELSE-FORMS is completely ignored -- it is not evaluated. (if (special-form-p 'if) "`if' is a special form" "`if' is not a special form") => "`if' is a special form" - Special Form: when CONDITION TRUE-FORMS... CONDITION is evaluated, if it is `t' the result of an implicit progn on the TRUE-FORMS is returned, otherwise `nil' is returned. (when t (message "Pointless") 'foo) => foo - Special Form: unless CONDITION ELSE-FORMS... This special forms first evaluates CONDITION, if its computed value is not `nil' its value is returned. Otherwise the ELSE-FORMS are evaluated sequentially, the value of the last is returned. - Special Form: cond CLAUSE... The `cond' special form is used to choose between an arbitrary number of conditions. Each CLAUSE is a list; its car is the CONDITION the list which is the cdr of the CLAUSE is the BODY-FORMS. This means that each CLAUSE looks something like: (CONDITION BODY-FORMS...) and a whole `cond' form looks like: (cond (CONDITION-1 BODY-FORMS-1...) (CONDITION-2 BODY-FORMS-2...) ...) The CONDITION in each CLAUSE is evaluated in sequence (CONDITION-1, then CONDITION-2, ...), the first one which evaluates to a non-`nil' has an implicit progn performed on its BODY-FORMS, the value of which is the value returned by the `cond' form. If the true CONDITION has no BODY-FORMS the value returned by `cond' is the value of the CONDITION. If none of the clauses has a non-`nil' CONDITION the value of the `cond' is `nil'. Often you want a "default" clause; one which has its BODY-FORMS to be evaluated if none of the other clauses are true. The way to do this is to add a clause with a CONDITION of `t' and BODY-FORMS of whatever you want the default action to be. (cond ((stringp buffer-list)) ;Clause with no BODY-FORMS ((consp buffer-list) (setq x buffer-list) ;Two BODY-FORMS t) (t ;Default clause (error "`buffer-list' is corrupted!"))) => t All of the other conditionals can be written in terms of `cond', (if C T E...) == (cond (C T) (t E...)) (when C T...) == (cond (C T...)) (unless C E...) == (cond (E) (t E...)) There are also a number of special forms which combine conditions together by the normal logical rules. - Special Form: or FORMS... The first of the FORMS is evaluated, if it is non-`nil' its value becomes the value of the `or' form and no more of `forms' are evaluated. Otherwise this step is repeated for the next member of FORMS. If all of the FORMS have been evaluated and none have a non-`nil' value `nil' becomes the value of the `or' form. If there are no FORMS `nil' is returned. (or nil 1 nil (beep)) ;`(beep)' won't be evaluated => 1 - Special Form: and FORMS... The first of the FORMS is evaluated. If it is `nil' no more of the FORMS are evaluated and `nil' becomes the value of the `and' structure. Otherwise the next member of FORMS is evaluated and its value tested. If none of the FORMS are `nil' the computed value of the last member of FORMS becomes the value of the `and' form. (and 1 2 nil (beep)) ;`(beep)' won't be evaluated => nil (and 1 2 3) ;All forms are evaluated => 3 - Function: not OBJECT This function inverts the boolean value of its argument. If OBJECT is non-`nil', `nil' is returned, otherwise `t' is returned. (not nil) => t (not t) => nil (not 42) => nil File: jade.info, Node: Looping Structures, Next: Non-Local Exits, Prev: Conditional Structures, Up: Control Structures Looping Structures ------------------ Jade's version of Lisp has only one structure for looping -- a "while" loop similar to those found in most programming languages. - Special Form: while CONDITION BODY-FORMS... The CONDITION form is evaluated. If it is non-`nil' an implicit progn is performed on the BODY-FORMS and the whole thing is repeated again. This continues until the CONDITION form evaluates to `nil'. The value of any `while' structure is `nil'. `while' can be recursively defined in terms of `when': (while C B ...) == (when C (progn B ... (while C B ...))) ;; Step through a list X (while X ;; Do something with the current element, `(car X)' (setq X (cdr X))) File: jade.info, Node: Non-Local Exits, Prev: Looping Structures, Up: Control Structures Non-Local Exits --------------- A "non-local exit" is a transfer of control from the current point of evaluation to a different point (somewhat similar to the much-maligned `goto' statement in some imperative languages). Non-local exits can either be used explicitly (`catch' and `throw') or implicitly (errors). * Menu: * Catch and Throw:: Programmed non-local exits * Function Exits:: Returning values from a function * Cleanup Forms:: Forms which will always be evaluated * Errors:: Signalling that an error occurred File: jade.info, Node: Catch and Throw, Next: Function Exits, Up: Non-Local Exits Catch and Throw ............... The `catch' and `throw' structures are used to perform explicit transfers of control. First a `catch' form is used to setup a "tag", this acts like a label for the C language's `goto' statement. To transfer control a `throw' form is then used to transfer to the named tag. The tag is destroyed and the `catch' form exits with the value provided by the `throw'. In a program this looks like, (catch 'TAG ;; Forms which may `throw' back to TAG ... (throw 'TAG VALUE) ;; Control has now passed to the `catch', ;; no more forms in this progn will be evaluated. ...) => VALUE where TAG is the tag to be used (this is normally a symbol) and VALUE is the result of the `catch' form. When a throw actually happens all catches in scope are searched for one with a tag which is `eq' to the tag in the throw. If more than one exists the most-recent is chosen. Now that the catch has been located the environment is `wound-back' to the catch's position (i.e. local variables are unbound, cleanup forms removed, unused catches forgotten, etc...) and all Lisp constructs between the current point of control and the catch are exited. For example, (let ((test 'outer)) (cons (catch 'foo (let ((test 'inner)) (throw 'foo test) (setq test 'unreachable))) ;Never reached test)) => (inner . outer) when the throw executes the second binding of `test' is unwound and the first binding comes back into effect. For more details on variable binding see *Note Local Variables::. Note that catch tags are *dynamically* scoped, the thrower does not have to be within the same lexical scope (this means you can throw through functions). - Special Form: catch TAG BODY-FORMS... This special form defines a catch tag which will be accessible while the BODY-FORMS are being evaluated. TAG is evaluated and recorded as the tag for this catch. Next the BODY-FORMS are evaluated as an implicit progn. The value of the `catch' form is either the value of the progn, or, if a `throw' happened, the value specified in the THROW form. Before exiting the tag installed by this form is removed. - Function: throw TAG &optional CATCH-VALUE This function transfers the point of control to the catch form with a tag which is `eq' to TAG. The value returned by this catch form is either CATCH-VALUE or `nil' if CATCH-VALUE is undefined. If there is no catch with a tag of TAG an error is signalled and the editor returns to the top-level of evaluation. File: jade.info, Node: Function Exits, Next: Cleanup Forms, Prev: Catch and Throw, Up: Non-Local Exits Function Exits .............. It is often useful to be able to immediately return control from a function definition (like the C `return' statement). Jade's version of Lisp has the `return' function for this. - Function: return &optional VALUE This function transfers control out of the most-recent lambda-expression (i.e. a function or macro definition) so that the result of the lambda- expression is VALUE. (funcall '(lambda () (return 'x) 'y)) => x The `'y' form is never evaluated since control is passed straight from the `(return 'y)' form back to the `funcall' form. File: jade.info, Node: Cleanup Forms, Next: Errors, Prev: Function Exits, Up: Non-Local Exits Cleanup Forms ............. It is sometimes necessary to be sure that a certain form is *always* evaluated, even when a non-local exit would normally bypass that form. The `unwind-protect' special form is used to stop this happening. - Special Form: unwind-protect BODY-FORM CLEANUP-FORMS... The BODY-FORM is evaluated, if it exits normally the CLEANUP-FORMS are evaluated sequentially then the value which the BODY-FORM returned becomes the value of the `unwind-protect' form. If the BODY-FORM exits abnormally though (i.e. a non-local exit happened) the CLEANUP-FORMS are evaluated anyway and the non-local exit continues. One use of this is to ensure that an opened file is always closed, for example, (catch 'foo (unwind-protect (let ((temporary-file (open (tmp-file-name) "w"))) ;; Use `temporary-file' (write temporary-file "A test\n") ;; Now force a non-local exit (throw 'foo)) ;; This is the CLEANUP-FORM it will *always* ;; be evaluated no matter what happens. (close temporary-file))) => nil File: jade.info, Node: Errors, Prev: Cleanup Forms, Up: Non-Local Exits Errors ...... Errors are a type of non-local exit; when a form can not be evaluated properly an error is normally "signalled". If an error-handler has been installed for that type of error control is unwound back to the handler and evaluation continues. If there is no suitable handler control is passed back to the event loop of the most-recent recursive edit and a suitable error message is printed. - Function: signal ERROR-SYMBOL DATA Signals that an error has happened. ERROR-SYMBOL is a symbol classifying the type of error, it should have a property `error-message' (a string) which is the error message to be printed. DATA is a list of objects which are relevant to the error -- they will be made available to any error-handler or printed with the error message otherwise. (signal 'void-value '(some-symbol)) error--> Value as variable is void: some-symbol - Variable: debug-on-error This variable is consulted by the function `signal'. If its value is either `t' or a list containing the ERROR-SYMBOL to `signal' as one of its elements, the Lisp debugger is entered. When the debugger exits the error is signalled as normal. When you expect an error to occur and need to be able to regain control afterwards the `error-protect' form can be used. - Special Form: error-protect BODY-FORM ERROR-HANDLERS... `error-protect' evaluates the BODY-FORM with error handlers in place. Each of the ERROR-HANDLERS is a list whose car is a symbol defining the type of error which this handler catches. The cdr of the list is a list of forms to be evaluated sequentially when the handler is invoked. While the forms of the error handler are being evaluated the variable `error-info' is bound to the value `(ERROR-SYMBOL . DATA)' (these were the arguments to the `signal' form which caused the error). The special value, the symbol `error', in the car of one of the ERROR-HANDLERS will catch *all* types of errors. (error-protect (signal 'file-error '("File not found" "/tmp/foo")) (file-error error-info) (error (setq x z))) ;Default handler => (file-error "File not found" "/tmp/foo") File: jade.info, Node: Variables, Next: Functions, Prev: Control Structures, Up: Programming Jade Variables ========= In Lisp symbols are used to represent variables. Each symbol contains a slot which is used to contain the value of the symbol when it is used as a symbol. The normal way to obtain the current value of a variable is simply to evaluate the symbol it lives in (i.e. write the name of the variable in your program). - Function: symbol-value VARIABLE This function returns the value of the symbol VARIABLE in the current environment. * Menu: * Local Variables:: Creating temporary variables * Setting Variables:: Altering a variable's value * Scope and Extent:: Technical jargon * Buffer-Local Variables:: Variables with distinct values in each buffer. * Void Variables:: Some variables have no values * Constant Variables:: Variables which may not be altered * Defining Variables:: How to define a variable before using it File: jade.info, Node: Local Variables, Next: Setting Variables, Up: Variables Local Variables --------------- A "local variable" is a variable which has a temporary value while a program is executing, for example, when a function is called the variables which are the names of its arguments are temporarily bound (a "binding" is a particular instance of a local variable) to the values of the arguments passed to the function. When the function call exits its arguments are unbound and the previous definitions of the variables come back into view. Even if a variable has more than one binding still `active' only the most recent is visible -- there is absolutely no way the previous bindings can be accessed until the bindings are unbound one-by-one. A nice way of visualising variable binding is to think of each variable as a stack. When the variable is bound to, a new value is pushed onto the stack, when it is unbound the top of the stack is popped. Similarly when the stack is empty the value of the variable is void (*note Void Variables::.). Assigning a value to the variable (*note Setting Variables::.) overwrites the top value on the stack with a new value. When the value of the variable is required it is simply read from the top of the stack. Apart from function calls there are two special forms which perform variable binding (i.e. creating local variables), `let' and `let*'. - Special Form: let BINDINGS BODY-FORMS... `let' creates new variable bindings as specified by the BINDINGS argument then evaluates the BODY-FORMS in order. The variables are then unbound to their state before this `let' form and the value of the implicit progn of the BODY-FORMS becomes the value of the `let' form. The BINDINGS argument is a list of the bindings to perform. Each binding is either a symbol, in which case that variable is bound to nil, or a list whose car is a symbol. The cdr of this list is a list of forms which, when evaluated, give the value to bind the variable to. (setq foo 42) => 42 (let ((foo (+ 1 2)) bar) ;; Body forms (setq foo (1+ foo)) ;This sets the new binding (cons foo bar)) => (4 . nil) foo => 42 ;The original values is back Note that no variables are bound until all the new values have been computed (unlike in `let*'). For example, (setq foo 42) => 42 (let ((foo 100) (bar foo)) (cons foo bar)) => (100 . 42) Although `foo' is given a new binding this is not actually done until all the new bindings have been computed, hence `bar' is bound to the *old* value of `foo'. - Special Form: let* BINDINGS BODY-FORMS... This special form is exactly the same as `let' except for one important difference: the new bindings are installed *as they are computed*. You can see the difference by comparing the following example with the last example in the `let' documentation (above), (setq foo 42) => 42 (let* ;Using `let*' this time ((foo 100) (bar foo)) (cons foo bar)) => (100 . 100) By the time the binding of `bar' is computed the new binding of `foo' has already been installed. File: jade.info, Node: Setting Variables, Next: Scope and Extent, Prev: Local Variables, Up: Variables Setting Variables ----------------- "Setting" a variable means to overwrite its current value (that is, the value of its most recent binding) with a new one. The old value is irretrievably lost (unlike when a new value is bound to a variable, *note Local Variables::.). - Special Form: setq VARIABLE FORM ... The special form `setq' is the usual method of altering the value of a variable. Each VARIABLE is set to the result of evaluating its corresponding FORM. The last value assigned becomes the value of the `setq' form. (setq x 20 y (+ 2 3)) => 5 In the above example the variable `x' is set to `20' and `y' is set to the value of the form `(+ 2 3)' (5). When the variable is marked as being buffer-local (*note Buffer-Local Variables::.) the current buffer's instance of the variable is set. - Function: set VARIABLE NEW-VALUE The value of the variable VARIABLE (a symbol) is set to NEW-VALUE and the NEW-VALUE is returned. This function is used when the VARIABLE is unknown until run-time, and therefore has to be computed from a form. (set 'foo 20) == (setq foo 20) ;`setq' means `set-quoted' => 20 File: jade.info, Node: Scope and Extent, Next: Buffer-Local Variables, Prev: Setting Variables, Up: Variables Scope and Extent ---------------- In Jade's version of Lisp all variables have "indefinite scope" and "dynamic extent". What this means is that references to variables may occur anywhere in a program (i.e. bindings established in one function are not only accessible within that function, that's lexical scope) and that references may occur at any point in the time between the binding being created and it being unbound. The combination of indefinite scope and dynamic extent is often termed "dynamic scope". As an aside, Lisp objects have "indefinite extent", meaning that the object will exist for as long as there is a possibility of it being referenced (and possibly longer -- until the garbage collector runs). Note that in Common Lisp only those variables declared `special' have indefinite scope and dynamic extent. Try not to abuse the dynamic scoping, although it is often very useful to be able to bind a variable in one function and use it in another this can be confusing if not controlled and documented properly. A quick example of the use of dynamic scope, (defun foo (x) (let ((foo-var (* x 20))) (bar x) ... (defun bar (y) ;; Since this function is called from ;; the function `foo' it can refer ;; to any bindings which `foo' can. (setq y (+ y foo-var)) ... File: jade.info, Node: Buffer-Local Variables, Next: Void Variables, Prev: Scope and Extent, Up: Variables Buffer-Local Variables ---------------------- It is often very useful to be able to give variables different values for different editor buffers -- most major modes need to record some buffer-specific information. Jade allows you to do this by giving a variable buffer-local bindings. There are two strengths of buffer-local variables: you can either give a variable a buffer-local value in a single buffer, with other buffers treating the variable as normal, or a variable can be marked as being *automatically* buffer-local, each time the variable is set the current buffer's value of the variable is updated. Each buffer maintains an alist of the symbols which have buffer-local values in the buffer and the actual values themselves, this alist may be read with the `buffer-variables' function. When the value of a variable is referenced (via the `symbol-value' function) the current buffer's alist of local values is examined for a binding of the variable being referenced; if one is found that is the value of the variable, otherwise the "default value" (the value stored in the symbol's value cell) is used. Setting a variable also searches for a buffer-local binding; if one exists its value is modified, not the default value. If the variable has previously been marked as being automatically buffer-local (by `make-variable-buffer-local') a buffer-local binding is automatically created if one doesn't already exist. Currently there is one main problem with buffer-local variables: they can't have temporary values bound to them (or rather, they can but I guarantee it won't work how you expect), so for the time being, don't try to bind local values (with `let' or `let*') to a buffer-local variable. - Function: make-local-variable SYMBOL This function gives the variable SYMBOL a buffer-local binding in the current buffer. The value of this binding will be the same as the variable's default value. If SYMBOL already has a buffer-local value in this buffer nothing happens. Returns SYMBOL. - Function: make-variable-buffer-local SYMBOL This function marks the variable SYMBOL as being automatically buffer-local. This means that any attempts at setting the value of SYMBOL will actually set the current buffer's local value (if necessary a new buffer-local binding will be created in the buffer). Returns SYMBOL. (make-variable-buffer-local 'buffer-modtime) => buffer-modtime - Function: default-value SYMBOL This function returns the default value of the variable SYMBOL. (setq foo 'default) => default (make-local-variable 'foo) ;Create a value in this buffer => foo (setq foo 'local) => local foo => local (symbol-value 'foo) => local (default-value 'foo) => default - Function: default-boundp SYMBOL Returns `t' if the variable SYMBOL has a non-void default value. - Special Form: setq-default SYMBOL FORM ... Similar to the `setq' special form except that the default value of each VARIABLE is set. In non-buffer-local symbols there is no difference between `setq' and `setq-default'. - Function: set-default SYMBOL NEW-VALUE Sets the default value of the variable SYMBOL to NEW-VALUE, then returns NEW-VALUE. - Function: kill-local-variable SYMBOL This function removes the buffer-local binding of the variable SYMBOL from the current buffer (if one exists) then returns SYMBOL. - Function: kill-all-local-variables This function removes all the buffer-local bindings associated with the current buffer. Subsequently, any buffer-local variables referenced while this buffer is current will use their default values. The usual way to define an automatically buffer-local variable is to use `defvar' and `make-variable-buffer-local', for example, (defvar my-local-variable DEFAULT-VALUE "Doc string for `my-local-variable'.") (make-variable-buffer-local 'my-local-variable) Note that if you want to reference the value of a buffer-local variable in a buffer other than the current buffer, use the `with-buffer' special form (*note The Current Buffer::.). For example, the form, (with-buffer OTHER-BUFFER SOME-VARIABLE) will produce the value of the variable SOME-VARIABLE in the buffer OTHER-BUFFER. File: jade.info, Node: Void Variables, Next: Constant Variables, Prev: Buffer-Local Variables, Up: Variables Void Variables -------------- A variable which has no value is said to be "void", attempting to reference the value of such a symbol will result in an error. It is possible for the most recent binding of a variable to be void even though the inactive bindings may have values. - Function: boundp VARIABLE Returns `t' if the symbol VARIABLE has a value, `nil' if its value is void. - Function: makunbound VARIABLE This function makes the current binding of the symbol VARIABLE be void, then returns VARIABLE. (setq foo 42) => 42 foo => 42 (boundp 'foo) => t (makunbound 'foo) => foo (boundp 'foo) => nil foo error--> Value as variable is void: foo File: jade.info, Node: Constant Variables, Next: Defining Variables, Prev: Void Variables, Up: Variables Constant Variables ------------------ In Lisp constants are represented by variables which have been marked as being read-only. Any attempt to alter the value of a constant results in an error. Two of the most commonly used constants are `nil' and `t'. - Function: set-const-variable VARIABLE &optional READ-WRITE This function defines whether or not the value of the symbol VARIABLE may be modified. If READ-WRITE is `nil' or undefined the variable is marked to be constant, otherwise it's marked to be a normal variable. The value returned is VARIABLE. - Function: const-variable-p VARIABLE Returns `t' if the value of the symbol VARIABLE may be altered, `nil' otherwise. Constants may behave a bit strangely when you compile the program they are used in: the value of the constant is likely to be hardwired into the compiled functions it is used in, and the constant is unlikely to be `eq' to itself! The compiler assumes that constant is always the same, whenever it is evaluated. It may even be evaluated more than once. *Note Compiled Lisp::. The special form `defconst' can be used to define constants, see *Note Defining Variables::. File: jade.info, Node: Defining Variables, Prev: Constant Variables, Up: Variables Defining Variables ------------------ The special forms `defvar' and `defconst' allow you to define the global variables which will be used in a program. This is entirely optional; it is highly recommended though. - Special Form: defvar VARIABLE FORM [DOC-STRING] This special form defines a global variable, the symbol VARIABLE. If the value of VARIABLE is void the FORM is evaluated and its value is stored as the value of VARIABLE (note that the default value is modified, never a buffer-local value). If the DOC-STRING argument is defined it is a string documenting VARIABLE. This string is then stored as the symbol's `variable-documentation' property and can be accessed by the `describe-variable' function. (defvar my-variable '(x y) "This variable is an example showing the usage of the `defvar' special form.") => my-variable - Special Form: defconst CONSTANT FORM [DOC-STRING] `defconst' defines a constant, the symbol CONSTANT. Its value (in the case of a buffer-local symbol, its default value) is set to the result of evaluating FORM. Note that unlike `defvar' the value of the symbol is *always* set, even if it already has a value. The DOC-STRING argument, if defined, is the documentation string for the constant. (defconst the-answer 42 "An example constant.") => the-answer *Note Constant Variables::. File: jade.info, Node: Functions, Next: Macros, Prev: Variables, Up: Programming Jade Functions ========= A "function" is a Lisp object which, when applied to a sequence of argument values, produces a value -- the function's "result". It may also produce side-effects. All Lisp functions return results -- there is nothing like a procedure in Pascal. Functions are the main building-block in Lisp programs, each program is usually a system of inter-related functions. There are two types of function: "primitive functions" are functions written in the C language, these are sometimes called built-in functions, the object containing the C code itself is called a "subr". All other functions are written in Lisp. - Function: functionp OBJECT Returns `t' if OBJECT is a function (i.e. it can be used as the function argument of `funcall'. (functionp 'set) => t (functionp 'setq) => nil (functionp #'(lambda (x) (+ x 2))) => t * Menu: * Lambda Expressions:: Structure of a function object * Named Functions:: Functions can be named by symbols, * Anonymous Functions:: Or they can be un-named * Predicate Functions:: Functions which return boolean values * Defining Functions:: How to write a function definition * Calling Functions:: Functions can be called by hand * Mapping Functions:: Map a function to the elements of a list File: jade.info, Node: Lambda Expressions, Next: Named Functions, Up: Functions Lambda Expressions ------------------ "Lambda expressions" are used to create an object of type function from other Lisp objects, it is a list whose first element is the symbol `lambda'. All functions written in Lisp (as opposed to the primitive functions in C) are represented by a lambda expression. Note that a lambda expression is *not* an expression, evaluating a lambda expression will give an error (unless there is a function called `lambda'). The format of a lambda expression is: (lambda LAMBDA-LIST [DOC] [INTERACTIVE-DECLARATION] BODY-FORMS... ) Where LAMBDA-LIST is the argument specification of the function, DOC is an optional documentation string, INTERACTIVE-DECLARATION is only required by editor commands (*note Commands::.) and the BODY-FORMS is the actual function code (when the function is called each form is evaluated in sequence, the last form's value is the result returned by the function). The LAMBDA-LIST is a list, it defines how the argument values applied to the function are bound to local variables which represent the arguments within the function. At its simplest it is simply a list of symbols, each symbol will have the corresponding argument value bound to it. For example, the lambda list, (lambda (x y) (+ x y)) takes two arguments, `x' and `y'. When this function is called with two arguments the first will be bound to `x' and the second to `y' (then the function will return their sum). To complicate matters there are several "lambda-list keywords" which modify the meaning of symbols in the lambda-list. Each keyword is a symbol whose name begins with an ampersand, they are: `&optional' All the variables following this keyword are considered "optional" (all variables before the first keyword are "required": an error will be signalled if a required argument is undefined in a function call). If an optional argument is undefined it will simply be given the value `nil'. Note that optional arguments must be specified if a later optional argument is also specified. Use `nil' to explicitly show that an optional argument is undefined. For example, if a function `foo' takes two optional arguments and you want to call it with only the second argument defined, the first argument must be specified as `nil' to ensure that the correct argument value is bound to the correct variable. (defun foo (&optional arg-1 arg-2) ... (foo nil arg-2-value) ;Leave the first argument undefined `&rest' The `&rest' keyword allows a variable number of arguments to be applied to a function, all the argument values which have not been bound to argument variables are simply consed into a list and bound to the variable after the `&rest' keyword. For example, in, (lambda (x &rest y) ...) the first argument, `x', is required. Any other arguments applied to this function are made into a list and this list is bound to the `y' variable. When a function represented by a lambda-list is called the first thing that happens is to bind the argument values to the argument variables. The LAMBDA-LIST and the list of argument values applied to the function are worked through in parallel. Any required arguments which are left undefined when the end of the argument values has been reached causes an error. After the arguments have been processed the BODY-FORMS are evaluated by an implicit progn, the value of which becomes the value of the function call. Finally, all argument variables are unbound and control passes back to the caller. File: jade.info, Node: Named Functions, Next: Anonymous Functions, Prev: Lambda Expressions, Up: Functions Named Functions --------------- Functions are normally associated with symbols, the name of the symbol being the same as the name of its associated function. Each symbol has a special function cell (this is totally separate from the symbol's value as a variable -- variables and functions may have the same name without any problems occurring) which is used to store the function's definition, either a lambda expression (*note Lambda Expressions::.) or a subr (C code) object. The evaluator knows to indirect through the function value of a symbol in any function call (*note Function Call Forms::.) so the normal way to call a function is simply write its name as the first element in a list, any arguments making up the other elements in the list. *Note List Forms::. The functions and special forms which take functions as their arguments (i.e. `funcall') can also take symbols. For example, (funcall 'message "An example") == (message "An example") - Function: symbol-function SYMBOL Returns the value of the function cell in the symbol SYMBOL. (symbol-function 'symbol-function) => #<subr symbol-function> - Function: fboundp SYMBOL This function returns `t' if the symbol SYMBOL has a non-void value in its function cell, `nil' otherwise. (fboundp 'setq) => t - Function: fset SYMBOL NEW-VALUE Sets the value of the function cell in the symbol SYMBOL to NEW-VALUE, then returns NEW-VALUE. This function is rarely used, see *Note Defining Functions::. - Function: fmakunbound SYMBOL This function makes the value of the function cell in SYMBOL void, then returns SYMBOL. File: jade.info, Node: Anonymous Functions, Next: Predicate Functions, Prev: Named Functions, Up: Functions Anonymous Functions ------------------- When giving function names as arguments to functions it is useful to give an actual function *definition* (i.e. a lambda expression) instead of the name of a function. In Lisp, unlike most other programming languages, functions have no inherent name. As seen in the last section named-functions are created by storing a function in a special slot of a symbol, if you want, a function can have many different names: simply store the function in many different symbols! So, when you want to pass a function as an argument there is the option of just writing down its definition. This is especially useful with functions like `mapcar' and `delete-if'. For example, the following form removes all elements from the LIST which are even and greater than 20. (setq LIST (delete-if #'(lambda (x) (and (zerop (% x 2)) (> x 20))) LIST)) The lambda expression is very simple, it combines two predicates applied to its argument. Note that the function definition is quoted by `#'', not the normal `''. This is a special shortcut for the `function' special form (like `'' is a shortcut to `quote'). In general, `#'X' is expanded by the Lisp reader to `(function X)'. - Special Form: function ARG This special form is nearly identical to the `quote' form, it always returns its argument without evaluating it. The difference is that the Lisp compiler knows to compile the ARG into a byte-code form (unless ARG is a symbol in which case it is not compiled). What this means is when you have to quote a function, use the `#'' syntax. File: jade.info, Node: Predicate Functions, Next: Defining Functions, Prev: Anonymous Functions, Up: Functions Predicate Functions ------------------- In Lisp, a function which returns a boolean `true' or boolean `false' value is called a "predicate". As is the convention in Lisp a value of `nil' means false, anything else means true. The symbol `t' is often used to represent a true value (in fact, sometimes the symbol `t' should be read as *any* non-`nil' value). Another Lisp convention is that the names of predicate functions should be the concept the predicate is testing for and either `p' or `-p'. The `p' variant is used when the concept name does not contain any hyphens. For example a predicate to test for the concept "const-variable" (a variable which has a constant value, *note Constant Variables::.) would be called `const-variable-p'. On the other hand a predicate to test for the concept "buffer" (a Lisp object which is a buffer) would be called `bufferp'. File: jade.info, Node: Defining Functions, Next: Calling Functions, Prev: Predicate Functions, Up: Functions Defining Functions ------------------ Named functions are normally defined by the `defun' special form. - Special Form: defun NAME LAMBDA-LIST BODY-FORMS... `defun' initialises the function definition of the symbol NAME to the lambda expression resulting from the concatenation of the symbol `lambda', LAMBDA-LIST and the BODY-FORMS. So, (defun foo (x y) ... == (fset 'foo #'(lambda (x y) ... The BODY-FORMS may contain a documentation string for the function as its first form and an interactive calling specification as its first (if there is no doc-string) or second form if the function may be called interactively by the user (*note Commands::.). An example function definition (actually a command) taken from Jade's source is, (defun upcase-word (count) "Makes the next COUNT words from the cursor upper-case." (interactive "p") (let ((pos (forward-word count))) (upcase-area (cursor-pos) pos) (goto-char pos))) File: jade.info, Node: Calling Functions, Next: Mapping Functions, Prev: Defining Functions, Up: Functions Calling Functions ----------------- Most of the time function calls are done by the evaluator when it detects a function call form (*note List Forms::.); when the function to be called is not known until run-time it is easier to use a special function to call the function directly than create a custom form to apply to the `eval' function. - Function: funcall FUNCTION &rest ARGS Applies the argument values ARGS to the function FUNCTION, then returns its result. Note that the argument values ARGS are *not* evaluated again. This also means that `funcall' can *not* be used to call macros or special forms -- they would need the unevaluated versions of ARGS, which are not available to `funcall'. (funcall '+ 1 2 3) => 6 - Function: apply FUNCTION &rest ARGS Similar to `funcall' except that the last of its arguments is a *list* of arguments which are appended to the other members of ARGS to form the list of argument values to apply to the function FUNCTION. Constructs a list of arguments to apply to the function FUNCTION from ARGS. File: jade.info, Node: Mapping Functions, Prev: Calling Functions, Up: Functions Mapping Functions ----------------- A "mapping function" applies a function to each of a collection of objects. Jade currently has two mapping functions, `mapcar' and `mapc'. - Function: mapcar FUNCTION LIST Each element in the list LIST is individually applied to the function FUNCTION. The values returned are made into a new list which is returned. The FUNCTION should be able to be called with one argument. (mapcar '1+ '(1 2 3 4 5)) => (2 3 4 5 6) - Function: mapc FUNCTION LIST Similar to `mapcar' except that the values returned when each element is applied to the function FUNCTION are discarded. The value returned is LIST. This function is generally used where the side effects of calling the function are the important thing, not the results. The two following functions are also mapping functions of a sort. They are variants of the `delete' function (*note Modifying Lists::.) and use predicate functions to classify the elements of the list which are to be deleted. - Function: delete-if PREDICATE LIST This function is a variant of the `delete' function. Instead of comparing each element of LIST with a specified object, each element of LIST is applied to the predicate function PREDICATE. If it returns `t' (i.e. not `nil') then the element is destructively removed from LIST. (delete-if 'stringp '(1 "foo" 2 "bar" 3 "baz")) => (1 2 3) - Function: delete-if-not PREDICATE LIST This function does the inverse of `delete-if'. It applies PREDICATE to each element of LIST, if it returns `nil' then the element is destructively removed from the list. (delete-if-not 'stringp '(1 "foo" 2 "bar" 3 "baz")) => ("foo" "bar" "baz") File: jade.info, Node: Macros, Next: Streams, Prev: Functions, Up: Programming Jade Macros ====== "Macros" are used to extend the Lisp language, they are basically a function which instead of returning its value, return a new form which will produce the macro call's value when evaluated. When a function being compiled calls a macro the macro is expanded immediately and the resultant form is open-coded into the compiler's output. * Menu: * Defining Macros:: Macros are defined like functions * Macro Expansion:: How macros are used by the evaluator * Compiling Macros:: The compiler expands macros at compile- time. File: jade.info, Node: Defining Macros, Next: Macro Expansion, Up: Macros Defining Macros --------------- Macros are defined in the same style as functions, the only difference is the name of the special form used to define them. A macro object is a list whose car is the symbol `macro', its cdr is the function which creates the expansion of the macro when applied to the macro calls unevaluated arguments. - Special Form: defmacro NAME LAMBDA-LIST BODY-FORMS... Defines the macro stored in the function cell of the symbol NAME. lAMBDA-LIST is the lambda-list specifying the arguments to the macro (*note Lambda Expressions::.) and BODY-FORMS are the forms evaluated when the macro is expanded. The first of BODY-FORMS may be a documentation string describing the macro's use. Here is a simple macro definition, it is a possible definition for the `when' construct (which might even be useful if `when' wasn't already defined as a special form...), (defmacro when (condition &rest body) "Evaluates CONDITION, if it's non-`nil' evaluates the BODY forms." (list 'if condition (cons 'progn body))) When a form of the type `(when C B ...)' is evaluated the macro definition of `when' expands to the form `(if C (progn B ...))' which is then evaluated to perform my when-construct. When you define a macro ensure that the forms which produce the expansion have no side effects; it would fail spectacularly when you attempt to compile your program!